home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
X User Tools
/
X User Tools (O'Reilly and Associates)(1994).ISO
/
sun4c
/
archive
/
tkman.z
/
tkman
/
man
/
cat1
/
tkman.1
Wrap
Text File
|
1994-09-22
|
28KB
|
727 lines
TKMAN(1) USER COMMANDS 14 Sep 1993
NAME
tkman - Tk-based manual page reader with hypertext
SYNOPSIS
A manual page browser, TkMan offers two major advantages
over xman: hypertext links to other man pages (click on a
word in the text which corresponds to a man page, and you
jump there), and better navigation within long man pages
with searches (both incremental and regular expression) and
jumps to section headers. TkMan also offers some conveni-
ence features, like a user-configurable list of commonly
used man pages, a one-click printout, and integration of
`whatis' and `apropos'. Further, one may highlight, as if
with a yellow marker, arbitrary passages of text in man
pages and subsequently jump directly to these passages by
selecting an identifying excerpt from a pulldown menu.
Finally, TkMan gives one control over the directory-to-menu
volume mapping of man pages with a capability similar to but
superior to xman's mandesc in that rather than forcing all
who share a man directory to follow a single organization,
TkMan gives control to the individual. In fact, one may
decide he has no use for a large set of man pages--say for
instance the programmer routines in volumes 2, 3, 4, 8--and
eliminate them from his personal database.
Since man page formatting follows conventions but not rigid
standards, not all man pages can be parsed fully. However,
most yield their section titles and SEE ALSOs and their
emphasized words. TkMan also tries to filter out the
unsightly page footers and headers put in by `nroff', but
nonstandard formatting can slip by.
This man page is slightly less current than the help page
available from within TkMan.
DESCRIPTION
Locating a man page
There are several ways to identify the manual page you
desire. You can type its name into the entry box at the top
of the screen and press return or click `man'. The name may
be just the name of the command or may include a `.n' or
`(n)' at the end where `n' specifies in which section to
look. Man pages are matched using file name globbing (as in
`csh'), so you can use `?' to match any single character,
`*' to match any (zero or more) characters, `[' .. `]' to
match any single character in the enclosed class, and `{' ..
`}' to expand the enclosed strings. If you're running TkMan
from a shell and giving it an initial man page name to load
up as an argument, use this syntax (adequately quoted for
protection from the shell), as opposed to the syntax of the
standard `man' command. Usually TkMan searches the
UCB 1
TKMAN(1) USER COMMANDS 14 Sep 1993
directories in your MANPATH environment variable for the man
page, but you may instead provide a path name for the man
page by beginning it with `~', `/', `.' or `..'; this is the
way to access a man page which isn't installed in a MANPATH
man directory. Further, other Tcl interpreters may display
a man page in TkMan by `send'ing a message to the function
`manShowMan' with the name of the desired man page, for
example `send tkman manShowMan tcl'. If multiple man page
names match the specification, the first match (as searched
for in MANPATH order) is shown and a pulldown menu appears
which contains a list of the other matches.
`apropos' information is available by typing the name and
clicking `apropos' or hitting meta-return (for meta informa-
tion, of course). The output of `apropos' is piped through
`sort' and `uniq' to remove duplicates. To pass the matches
through another filter, simply give the pipe as in a shell,
e.g., `search | grep ^g' (each space character is signifi-
cant) returns all the search-related commands which begin
with the letter `g'. Hypertext is active within this list-
ing also.
The `Paths' pulldown gives you complete control over which
directories of your MANPATH are searched for man pages and
apropos information. You can call up a listing of all man
pages in a volume through the `Volumes' pulldown menu and
then select one to view by double-clicking on its name.
Typing a letter jumps to the line in the listing starting
with that letter (capital and lower case letters are dis-
tinct). The `all' pseudo volume can be useful when used
with `Paths' to obtain a complete listing of man pages in,
say, one directory tree.
Once you have a man page name in the text display box,
whether from apropos, a volume listing or a reference within
another man page, you can double-click on it to hypertext-
jump to it.
The last few man pages you looked at can be accessed
directly through the `History' pulldown menu. `Shortcuts'
lists your personal favorites and is used just like `His-
tory', with the additional options of adding (by clicking
`+') the current man page or removing (`-') it from the
list.
(Man pages specified as above are processed through an
`nroff' filter. TkMan can also read raw text from a file or
from a command pipeline, which can then be read, searched
and highlighted same as a man page. To read from a file,
make the first character in the name a `<', as in
`<~/foo.txt'. To open a pipe, make the first character a
`|' (vertical bar), as in `|gzcat foo.txt.gz' or `|cat
UCB 2
TKMAN(1) USER COMMANDS 14 Sep 1993
../foo.txt | grep bar' (that's no space after the first `|',
a space before and after any subsequent ones). After read-
ing a file, the current directory is set to its directory.
Commands are not processed by a shell, but the metacharac-
ters `.', `..', `~' and `$' (for environment variables), are
expanded nonetheless. Typing is eased further by file name
completion, bound to the escape key. Lone files (i.e., not
part of a pipe) are automatically uncompressed--no need to
read compressed files through a `zcat' pipe. It is not
expected that reading raw text will be done much; it is
included so the occasional non-man page documentation may be
read from the same environment. For more sophisticated file
browsing, use NBT, my Tcl/Tk-based file browser, which
available from TkMan's home FTP site, mentioned above.)
Working within a man page
The `whatis' information for a man page, if any, appears at
the top of the screen.
To the extent it follows convention, the man page is parsed
to yield its section and subsection titles (which are
directly available from the `Sections' pulldown) and refer-
ences to other man pages from its SEE ALSO section (`Links'
pulldown). One may jump directly to a section within a man
page or a man page referenced in the SEE ALSO section,
respectively, by selecting the corresponding entry from one
of these pulldowns. It may be handy to tear off the `Sec-
tions' and `Links' menus (by dragging the menu title with
mouse button 2 pressed).
Within a man page or raw text file or pipe, you may added ad
hoc highlighting, as though with a yellow marker (underlin-
ing on monochrome monitors). Highlighted regions may then
be scrolled to directly through the `Highlights' pulldown
menu. To highlight a region, select the desired text by
clicking button 1, dragging to the far extent of the desired
region, releasing the button, then clicking on the `+' next
to `Highlights'. To remove any highlights or portions
thereof in a region, select it as before but then click on
`-'. Highlighting information is persistent across execu-
tions of TkMan.
You can move about the man page by using the scrollbar, or
typing a number of key combinations familiar to Emacs afi-
cionados. Space or C-v page down and delete or M-v page up.
C-n and C-p scroll up and down, respectively, by a single
line. M-< goes to the head and M-> to the tail of the text.
One may "scan" the page by dragging up and down with the
middle mouse button pressed. Like Emacs, C-space will mark
one's current location, which can be returned to later with
UCB 3
TKMAN(1) USER COMMANDS 14 Sep 1993
C-x, which exchanges the then-current position with the
saved mark; a second C-x swaps back.
C-s initiates a search. Subsequently typing a few letters
attempts to find a line with that string, starting its
search with the topmost line currently visible. A second
C-s finds the next match of the string typed so far. (If
the current search string is empty, a second C-s retrieves
the previous search pattern.) C-r is similar to C-s but
searches backwards. Escape or C-g cancels the search. This
incremental search can be used to quickly locate a particu-
lar command-line option or a particular command in a group
(as in `csh'). At the bottom of the screen, type in a regu-
lar expression to search for and hit return or click
`Search' to begin a search. Hit `Next' or keep hitting
return to search for the next occurance. [`Prev' will be
added when Tk supports a `tag prevrange' command.]
The tab key moves the focus from the man page type-in line
to the text view of the man page to the search line and back
around.
Other commands
The `Occasionals' menu holds commands and options which you
probably won't use much. The first group in this menu is
comprised of commands which you may invoke several times in
a single TkMan session. `Help' returns to this information
screen. Although virtually made obsolete by TkMan, `Print'
makes a copy of the current man page on dead trees, helping
to starve the planet of life-giving oxygen. By default,
incremental searching is not case sensitive, but regular
expression searching is; these settings can be toggled with
the next two menu checkboxes. If you install a new manual
pages, invoking `Rebuild Database' will permit them to show
up the next time that volume list is shown and be found in
the next search without the bother of re-executing TkMan.
Usually TkMan saves its persistent variables, only and
always, when exited with the `Quit' button. One may guard
against losing highlighting, shortcuts and other what-
should-be persistent information by checkpointing the
current state with the "Update operation, obviously.
Like `xman' one may instantiate multiple viewers. When
there is more than one viewer you may choose man pages in
one viewer and have their contents shown in another. Use
the `Output' pulldown (which appears and disappears as
relevant) to direct one viewer's output destination to
another. With this feature one may easily compare two simi-
lar man pages for differences, keep one man page always
visible, or examine several man pages from a particular
UCB 4
TKMAN(1) USER COMMANDS 14 Sep 1993
volume listing or a SEE ALSO section. `Output' only affects
the display destination of man pages.
You will probably only use commands in the next two clusters
of `Occasionals' once or twice and leave them set for all
executions of TkMan. Choose between seeing a man page's
`whatis' information and the full path name of the found
file with the `Show Path of Found Man' switch. Until `wish'
has an option to startup iconified, TkMan has a checkbox for
that. Subsection parsing doesn't work for all varieties of
man page macros formatting, but it can usefully augment the
Sections listing for long man pages. At the factory, TkMan
is set to format the contents of man volumes on demand,
which entails a little wait the first time that volume is
shown, as opposed to waiting for all volumes to be loaded at
startup but no waiting thereafter; the `Preformat Volumes'
switch chooses between these. If a man page has not been
formatted by `nroff', TkMan must first pipe the source text
through `nroff'. By turing on `Save on nroff', the
`nroff'-formatted text is saved to disk (if possible),
thereby eliminating this time-consuming step the next time
the man page is read.
`Mono' toggles between the proportionally-spaced font and a
monospaced one, for use in those man pages that rely on a
constant-width font to align columns [when Tk supports tabs
better, the need for this will diminish]. `Quit' exits
TkMan, of course, after saving some status information (see
below). To exit without saving status information, select
the `Quit' option from the `Occasionals' pulldown.
Customizing TkMan
There are three levels of configuration to TkMan.
(1) Transparent. Simply use TkMan and it will remember your
window size and placement and short cuts (if you quit out of
TkMan via the `Quit' button).
(2) Configuration file. Most interesting persistent infor-
mation, like the command(s) used to print the man page, the
fonts used, and some key bindings, can be changed by editing
one's own ~/.tkman. Thus, a single copy of TkMan (i.e., the
executable `tkman') can be shared, but each user can have
his own customized setup. (The file ~/.tkman is
created/rewritten every time one quits TkMan via the `Quit'
button in the lower right corner. Thus, to get a ~/.tkman
to edit, first run and quit TkMan. Do not create one from
scratch as it will not have the proper format used for
UCB 5
TKMAN(1) USER COMMANDS 14 Sep 1993
saving other persistent information, and your work will be
overwritten, which is to say lost.)
Most persistent information can be changed in the obvious
way. For example, to change the means of highlighting from
a light yellow background to an underline (to display better
on a monochrome monitor), EDIT (change in place) `set
man(show,highlight) {-background #ffd8ffffb332}' to `set
man(show,highlight) {-underline yes}' I find that dark text
is easier to read: `set man(show,fontcolor) black'
To change colors append `option' commands to ~/.tkman.
Alternatively, TkMan also works with standard X11 resources.
For instance, this is how I set my foreground and background
colors (X11 resource lines should be placed in one's `.Xde-
faults' file, not in ~/.tkman):
*TkMan*Foreground: SlateGray4 *TkMan*Background: beige
Additional useful commands include `wm', which deals with
the window manager; and `bind', which changes keyboard and
mouse bindings not related to the text display window. For
example, to set an icon image for TkMan, add this line to
the end of ~/.tkman:
`wm iconbitmap .man @/some/directory/TkMan.xpm'
(3) Source code. Of course, but if you make generally use-
ful changes or have suggestions for some, please report them
back to me so I may share the wealth with the next release.
Command line options
`-title <title>' Place `<title>' in the window's title bar.
`-iconify' and `--iconify' Start up iconified or uniconified
(the default), respectively.
`-iconname <name>' Use `<name>' in place of the uniconified
window's title for the icon name.
`-iconbitmap <bitmap-path>' and `-iconmask <bitmap-path>'
Specify the icon bitmap and its mask.
`-v' Show the current version of TkMan and exit.
`-M <path-list>' `-M+ <path-list>' As with `man', change the
search path for manual pages to the given colon-separated
list of directory subtrees. The `-M+' option prepends these
UCB 6
TKMAN(1) USER COMMANDS 14 Sep 1993
directories to the current list.
There is no `-geometry' option. To assign a persistent
geometry, start up TkMan, size and place the window as
desired, then (this is important) quit via the `Quit' button
in the lower right corner.
Key bindings
Key bindings related to the text display box are kept in the
`sb' array in ~/.tkman (see the Tcl documentation for more
information on Tcl arrays). In editing the `sb(key,...)'
keyboard bindings, modifiers MUST be listed in the following
order: `M' (for meta), `C' (control), `A' (alt), `S'
(shift). For instance, `set sb(key,MS-less) pagestart' is a
valid binding, whereas `set sb(key,SM-less)' is not. To
make a binding without a modifier key, precede the character
by `-', as in `set sb(key,-space) pagedown'. If you have
NBT and would like to share key bindings between them, save
the keybindings in their own file, then `source' this file
at the bottom of ~/.tkman.
Tkmandesc
Like `xman', TkMan gives you directory-by-directory control
over named volume contents. Unlike and superior to `xman',
however, each individual controls directory-to-volume place-
ment, rather than facing a single specification for each
directory tree that must be observed by all.
By default a matrix is created by taking the product of
directories in the MANPATH crossed with volume names, with
the yield of each volume containing all the corresponding
subdirectories in the MANPATH. By adding Tcl commands to
your ~/.tkman (see above), you may add new volume names and
add, move, copy and delete directories to/from/among direc-
tories.
The interface to this functionality takes the form of Tcl
commands, so you may need to learn Tcl--particularly the
sections on Tcl lists and, perhaps, iteration (`foreach' or
`for')--to use this facility to its fullest.
Directory titles and SINGLE LETTER abbrevations are kept in
lists. Letters MUST be unique (capital letters are distinct
from lower case), but need not correspond to actual direc-
tories. In fact, volume letters specified here supercede
the defaults in identifying a volume in man page searches.
UCB 7
TKMAN(1) USER COMMANDS 14 Sep 1993
COMMANDS
These commands are added to the file ~/.tkman (see Customiz-
ing TkMan, above).
To set absolutely the volume names for which all directories
should be searched, EDIT the parallel arrays on these EXIST-
ING lines: `set man(manList) ...' `set man(manTitleList)
...'
To recreate a cross product of current section lists: `man-
DescDefaults'
To add "pseudo" sections to default/current volume name
list, at the end of the list, in alphabetical order, or
before or after a specific volume: `set manDescAddSects
<list of <letter, title pairs>>' or `set manDescAddSects
<list of <letter, title pairs>> sort' or `set manDes-
cAddSects <list of <letter, title pairs>> before <sect-
letter>' or `set manDescAddSects <list of <letter, title
pairs>> after <sect-letter>'
To move/copy/delete/add directories: `manDescMove <from-
list> <to-list> <dir-patterns>' `manDescCopy <from-list>
<to-list> <dir-patterns>' `manDescDelete <from-list> <dir-
patterns>' `manDescAdd <to-list> <dir-list>'
The `<dir-patterns>' uses the same meta characters as man
page searching (see above). It is matched against MANPATH
directories with volume subdirectory appended, as in
`/usr/man/man3'. `<from-list>' and `<to-list>' are Tcl
lists of the unique single letter volume names; `*' is an
abbreviation for all volumes.
Warning: Moving directories from their natural home slightly
impairs searching speed when following a reference within a
man page. For instance, say you've moved man pages for X
Windows subroutines from their natural home in volume 3 to
their own volume called "X". Following a reference in
`XButtonEvent' to `XAnyEvent(3X11)' first searches volume 3;
not finding it, TkMan searches all volumes and finally finds
it in volume X. With no hint to look in volume 3 (as given
by the `3X11' suffix), the full volume search would have
begun straight away. (Had you double-clicked in the volume
listing for volume X or specified the man page as
`XButtonEvent.X', volume X would have been searched first,
successfully.)
To help debug tkmandesc scripts, you may invoke `man-
DescShow' to dump to stdout the current correspondence of
directories to volumes names.
UCB 8
TKMAN(1) USER COMMANDS 14 Sep 1993
EXAMPLES
(1) To collect together all man pages in default volumes 2
and 3 in all directories into a volume called "Programmer
Subroutines", add these lines to the tail of ~/.tkman:
`manDescAddSects {{p "Programmer Subroutines"}}' `man-
DescMove {2 3} p *'
To place the new section at the same position in the volume
pulldown list as volumes 2 and 3: `manDescAddSects {{p "Pro-
grammer Subroutines"}} after 2' `manDescMove {2 3} p *'
To move only a selected set of directories: `manDescAddSects
{{p "Programmer Subroutines"}}' `manDescMove * p
{/usr/man/man2 /usr/local/man/man3}'
(2) To have a separate volume with all of your and a
friend's personal man pages, keeping with a duplicate in
their default locations:
`manDescAddSects {{t "Man Pages du Tom"} {b "Betty
Page(s)"}}' `manDescCopy *phelps* t *' `manDescCopy *page* t
*'
(3) To collect the X windows man pages into two sections of
their own, one for programmer subroutines and another for
the others.
`manDescAddSects {{x "X Windows"}} after 1' `manDescAddSects
{{X "X Subroutines"}} after 3' `manDescMove * x *X11*' `man-
DescMove x X *3'
We must name the X Subroutines volume "X", not "x" or "xsub"
as the former would duplicate the letter used for other X
man pages and the latter is a string of multiple letters.
(4) If you never use the programmer subroutines, why not
save time and memory by not reading them into the database?
`manDescDelete * {*[2348]}; # braces prevent Tcl from trying
to execute [2348]'
Alternatively but not equivalently: `manDescDelete {2 3 4 8}
*'
UCB 9
TKMAN(1) USER COMMANDS 14 Sep 1993
Tkmandesc vs. xman and SGI
TkMan's `tkmandesc' capability is patterned after xman's
mandesc files. By placing a mandesc file at the root of a
man page directory tree, one may create pseudo volumes and
move and copy subdirectories into them. Silicon Graphics
has modified xman so that simply by creating a subdirectory
in a regular man subdirectory one creates a new volume.
This is evil. It violates the individual user's rights to
arrange the directory-volume mapping as he pleases, as the
mandesc file or subdirectory that spontaneously creates a
volume is set a single place and must be observed by all who
read that directory. By contrast, TkMan places the
directory-to-volume mapping control in an individual's own
~/.tkman file. This gives the individual complete control
and inflicts no pogrom on others who share man page direc-
tories. Therefore, mandesc files are not supported in any
way by TkMan.
One may still share custom setups, however, by sharing the
relevant lines of ~/.tkman. In fact, a tkmandesc version of
the standard SGI man page directory setup is included in the
`contrib' directory of the TkMan distribution. For assis-
tance with SGI-specific directory manipulation, contact Paul
Raines (raines@bohr.physics.upenn.edu).
AUTHOR
Tom Phelps
University of California, Berkeley
Computer Science Division
571 Evans Hall
Berkeley, CA 94720
USA
(510) 642-8155
phelps@cs.Berkeley.EDU
AVAILABILITY
The latest version of TkMan is always available by anonymous
FTP at ftp.cs.Berkeley.EDU in the /ucb/mhgs directory.
SEE ALSO
man(1), man(7), catman(8), xman(1)
UCB 10
TKMAN(1) USER COMMANDS 14 Sep 1993
COPYRIGHT
Copyright (c) 1993 T.A. Phelps University of California,
Berkeley Department of Electrical Engineering and Computer
Science Computer Science Division
PERMISSION IS GRANTED TO DISTRIBUTE THIS SOFTWARE FREELY,
BUT ONE MAY NOT CHARGE FOR IT OR INCLUDE IT WITH SOFTWARE
WHICH IS SOLD.
If you send me bug reports and/or suggestions for new
features, include the versions of TkMan, Tcl, Tk, X, and
UNIX, your machine and X window manager names, and a copy of
your ~/.tkman file. First check that values changed in the
Makefile or source code aren't being unexpectedly overridden
in ~/.tkman.
DISCLAIMER
Permission to use, copy, modify, and distribute this
software and its documentation for educational, research and
non-profit purposes, without fee, and without a written
agreement is hereby granted, provided that the above copy-
right notice and the following three paragraphs appear in
all copies.
Permission to incorporate this software into commercial pro-
ducts may be obtained from the Office of Technology Licens-
ing, 2150 Shattuck Avenue, Suite 510, Berkeley, CA 94704.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO
ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CON-
SEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE
AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WAR-
RANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRAN-
TIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR-
POSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.
UCB 11